---
title: "digger.yml"
---

You can configure Digger by dropping a `digger.yml` file at the root level of your repo

```yml
projects:
  - name: my-first-app
    dir: app-one
  - name: my-second-app
    dir: app-two
auto_merge: true
```

**Note:** you can also name your Digger configuration file differently, and specify its name using the `digger-filename` input at GitHub Action level.

---

## Example using all keys

```yml
traverse_to_nested_projects: true
auto_merge: false
pr_locks: true
projects:
  - name: prod
    dir: prod
    apply_requirements: [approved, mergeable, undiverged]
    branch: main
    workspace: default
    terragrunt: false
    workflow: prod
    include_patterns: ["../modules/**"]
    exclude_patterns: []
  - name: staging
    dir: staging
    branch: main
    workflow: staging
    include_patterns: ["../modules/**"]
    exclude_patterns: []    
generate_projects:
  include: "../projects/**"
  exclude: "../.terraform/**"
workflows:
  staging:
    env_vars:
      state:
        - name: TF_LOG
          value: trace
      commands:
        - name: TF_LOG
          value: trace
    plan:
      steps:
        - init:
          extra_args: ["backend-config=../backend.hcl"]
        - run: "echo hello world"
        - plan
    apply:
      steps:
        - run: "echo hello world"
          shell: zsh
        - init
        - apply:
          extra_args: ["-compact-warnings"]
    workflow_configuration:
      on_pull_request_pushed: ["digger plan"]
      on_pull_request_closed: ["digger unlock"]
      on_commit_to_default: ["digger apply"]
  prod:
    env_vars:
      state:
        - name: AWS_ACCESS_KEY_ID
          value_from: PROD_BACKEND_TF_ACCESS_KEY_ID
        - name: AWS_SECRET_ACCESS_KEY
          value_from: PROD_BACKEND_TF_SECRET__ACCESS_KEY
      commands:
        - name: AWS_ACCESS_KEY_ID
          value_from: PROD_TF_ACCESS_KEY_ID
        - name: AWS_SECRET_ACCESS_KEY
          value_from: PROD_TF_SECRET_ACCESS_KEY
    plan:
      steps:
        - run: "checkov -d ."
        - init
        - plan
    apply:
      steps:
        - run: "terraform fmt -check -diff -recursive"
          shell: zsh
        - init
        - apply
    workflow_configuration:
      on_pull_request_pushed: ["digger plan"]
      on_pull_request_closed: ["digger unlock"]
      on_commit_to_default: ["digger unlock"]
```

## Reference

### Top-level

| Key                         | Type                                                          | Default  | Required | Description                                                                                                                            | Notes                                         |
|-----------------------------|---------------------------------------------------------------|----------|----------|----------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------|
| telemetry                   | boolean                                                       | true     | no       | allows collecting anonymised usage and debugging data                                                                                  |                                               |
| auto_merge                  | boolean                                                       | false    | no       | automatically merge pull requests when all checks pass                                                                                 |                                               |
| auto_merge_strategy         | string                                                        | "squash" | no       | The merge strategy to use while automerging, defaults to "squash". Possible values: 'squash', 'merge' (for merge commits) and 'rebase' | currently only github supported for this flag |
| pr_locks                    | boolean                                                       | true     | no       | Enable PR-level locking                                                                                                                |                                               |
| delete_prior_comments       | boolean                                                       | false    | no       | Enables digger to delete previous comments to reduce noise in the PR                                                                   |                                               |
| projects                    | array of [Projects](/ce/reference/digger.yml#project)         | \[\]     | no       | list of projects to manage                                                                                                             |                                               |
| generate_projects           | [GenerateProjects](/ce/reference/digger.yml#generateprojects) | {}       | no       | generate projects from a directory structure                                                                                           |                                               |
| workflows                   | map of [Workflows](/ce/reference/digger.yml#workflows)        | {}       | no       | workflows and configurations to run on events                                                                                          |                                               |
| traverse_to_nested_projects | boolean                                                       | false    | no       | enabled traversal of nested directories                                                                                                |                                               |

### Project

| Key                      | Type                                                 | Default | Required | Description                                                        | Notes                                                                                                     |
| ------------------------ | ---------------------------------------------------- | ------- | -------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| name                     | string                                               |        | yes      | name of the project                                                | must be unique                                                                                             |
| branch                   | string                                               |        | yes      | the target branch to match this project on                         | This field is optional and defaults to the repository's default branch when not set                        |
| dir                      | string                                               |        | yes      | directory containing the project                                   |                                                                                                            |
| apply_requirements       | []string                                             | [mergeable]       | no      | list of requirements to be met before merged                                   |  see [apply requirements](/ce/howto/apply-requirements) for details                  |
| workspace                | string                                               | default | no       | terraform workspace to use                                         |                                                                                                           |
| opentofu                 | boolean                                              | false   | no       | whether to use opentofu                                            |                                                                                                           |
| terragrunt               | boolean                                              | false   | no       | whether to use terragrunt                                          |                                                                                                           |
| workflow                 | string                                               | default | no       | workflow to use                                                    | default workflow will be created for you described in workflow section                                    |
| include\_patterns        | array of strings                                     | \[\]    | no       | list of directory glob patterns to include, e.g. `./modules`       | see [Include / Exclude Patterns](/ce/howto/include-exclude-patterns)                                         |
| exclude\_patterns        | array of strings                                     | \[\]    | no       | list of directory glob patterns to exclude, e.g. `.terraform`      | see [Include / Exclude Patterns](/ce/howto/include-exclude-patterns)                                         |
| depends\_on              | array of strings                                     | \[\]    | no       | list of project names that need to be completed before the project | it doesn't force terraform run, but affects the order of commands for projects modified in the current PR |
| aws_role_to_assume       | [RoleToAssume](/ce/reference/digger.yml#roletoassume)   |         | no       | A string representing the AWS role to assume for this project      |                                                                                                           |

### GenerateProjects

| Key     | Type                                               | Default | Required | Description                         | Notes |
| ------- | -------------------------------------------------- | ------- | -------- | ----------------------------------- | ----- |
| include | string                                             |         | no       | glob pattern to include directories |       |
| exclude | string                                             |         | no       | glob pattern to exclude directories |       |
| blocks  | array of [Block](/ce/reference/digger.yml#block)   | \[\]    | no       | list of blocks to generate projects |       |

### Block

| Key                | Type                                                  | Default | Required | Description                                                   | Notes                                                                  |
| ------------------ | ----------------------------------------------------- | ------- | -------- | ------------------------------------------------------------- | ---------------------------------------------------------------------- |
| block_name         | string                                                |         | no       | name of the block                                             |                                                                        |
| workflow           | string                                                | default | no       | workflow to use                                               | default workflow will be created for you described in workflow section |
| workflow_file      | string                                                |         | no       | name of workflow file for GitHub Actions                      |                                                                        |
| aws_role_to_assume | [RoleToAssume](/ce/reference/digger.yml#roletoassume) |         | no       | A string representing the AWS role to assume for this project |                                                                        |
| include            | string                                                |         | no       | glob pattern to include directories                           | only for terraform and opentofu                                        |
| exclude            | string                                                |         | no       | glob pattern to exclude directories                           | only for terraform and opentofu                                        |
| opentofu           | boolean                                               | false   | no       | whether to use opentofu                                       | only for opentofu                                                      |
| terragrunt         | boolean                                               | false   | no       | whether to use terragrunt                                     | only for terragrunt                                                    |
| root_dir           | string                                                |         | no       | root directory of terragrunt projects                         | only for terragrunt                                                    |

### Workflows

| Key                    | Type                                                                 | Default | Required | Description                                | Notes |
| ---------------------- | -------------------------------------------------------------------- | ------- | -------- | ------------------------------------------ | ----- |
| env_vars               | [EnvVars](/ce/reference/digger.yml#envvars)                             | {}      | no       | environment variables to set for per stage |       |
| plan                   | [Plan](/ce/reference/digger.yml#plan)                                   | {}      | no       | plan stage configuration                   |       |
| apply                  | [Apply](/ce/reference/digger.yml#apply)                                 | {}      | no       | apply stage configuration                  |       |
| workflow_configuration | [WorkflowConfiguration](/ce/reference/digger.yml#workflowconfiguration) | {}      | no       | describes how to react to CI events        |       |

### EnvVars

| Key      | Type                                            | Default | Required | Description                                               | Notes                                                                     |
| -------- | ----------------------------------------------- | ------- | -------- | --------------------------------------------------------- | ------------------------------------------------------------------------- |
| state    | array of [EnvVar](/ce/reference/digger.yml#envvar) | \[\]    | no       | environment variables to set for terraform init stage     | can be use to set different credentials for remote backend for example    |
| commands | array of [EnvVar](/ce/reference/digger.yml#envvar) | \[\]    | no       | environment variables to set for other terraform commands | can be use to set different credentials for actual managed infrastructure |

### EnvVar

| Key        | Type   | Default | Required | Description                                                  | Notes                                                                                                                                                                                                                                                                                                               |
| ---------- | ------ | ------- | -------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name       | string |         | yes      | name of the environment variable                             |                                                                                                                                                                                                                                                                                                                     |
| value_from | string |         | yes      | name of the other environment variable to get the value from | this can be used for secrets. For example you set a secret from some secret manager (e.g. github secrets) as environment variable and the remap it to another variable. E.g. setting DEV_TF_ACCESS_KEY as a secret in github action, but then remap it into AWS_ACCESS_KEY during terraform apply command execution |
| value      | string |         | yes      | value of the environment variable                            | this value will have a preference over value_from field if both are set                                                                                                                                                                                                                                             |

### RoleToAssume

| Key     | Type   | Default | Required | Description                                              | Notes                                                |
| ---------------- | ------ | ------- | -------- | -------------------------------------------------------- | ---------------------------------------------------- |
| aws_role_region  | string |         | no       | Regions used when performing sts web identity calls      |   This will default to  "us-east-1" if not set       |
| state            | string |         | yes      | ARN of the role to assume for state backend              |   You can optionally set role and the same role      |
| command          | string |         | yes      | ARN of the role to assume for commands e.g. plan / apply |   will be used for both.                             |

### Plan

| Key   | Type                                        | Default | Required | Description                            | Notes |
| ----- | ------------------------------------------- | ------- | -------- | -------------------------------------- | ----- |
| steps | array of [Step](/ce/reference/digger.yml#step) | \[\]    | no       | list of steps to run during plan stage |       |

### Apply

| Key   | Type                                        | Default | Required | Description                             | Notes |
| ----- | ------------------------------------------- | ------- | -------- | --------------------------------------- | ----- |
| steps | array of [Step](/ce/reference/digger.yml#step) | \[\]    | no       | list of steps to run during apply stage |       |

### WorkflowConfiguration

| Key                    | Type                                                                    | Default | Required | Description                                                          | Notes |
| ---------------------- | ----------------------------------------------------------------------- | ------- | -------- | -------------------------------------------------------------------- | ----- |
| on_pull_request_pushed | array of enums\[digger plan, digger apply, digger lock, digger unlock\] | \[\]    | no       | list of stages to run when pull request is pushed                    |       |
| on_pull_request_closed | array of enums\[digger plan, digger apply, digger lock, digger unlock\] | \[\]    | no       | list of stages to run when pull request is closed                    |       |
| on_commit_to_default   | array of enums\[digger plan, digger apply, digger lock, digger unlock\] | \[\]    | no       | list of stages to run when commit is pushed to default branch        |       |
| skip_merge_check       | boolean                                                                    | false   | no       | Allow a workflow to skip mergeability checks and run digger commands |       |

### Step

| Key   | Type                                                               | Default         | Required | Description          | Notes                                              |
| ----- | ------------------------------------------------------------------ | --------------- | -------- | -------------------- | -------------------------------------------------- |
| init  | [Init](/ce/reference/digger.yml#init-apply-plan-as-object)/string  | \{\} OR ""      | no       | terraform init step  | if missing from array of steps, it will be skipped |
| plan  | [Plan](/ce/reference/digger.yml#init-apply-plan-as-object)/string  | \{\} OR ""      | no       | terraform plan step  | if missing from array of steps, it will be skipped |
| apply | [Apply](/ce/reference/digger.yml#init-apply-plan-as-object)/string | \{\} OR ""      | no       | terraform apply step | if missing from array of steps, it will be skipped |
| run   | [Run](/ce/reference/digger.yml#run-as-object)/string               | \{\} OR ""      | no       | shell command to run | if missing from array of steps, it will be skipped |

### Init/Apply/Plan as object

| Key        | Type             | Default | Required | Description                                          | Notes |
| ---------- | ---------------- | ------- | -------- | ---------------------------------------------------- | ----- |
| extra_args | array of strings | \[\]    | no       | extra arguments to pass to terraform init/plan/apply |       |

### Run as object

| Key   | Type   | Default | Required | Description                     | Notes         |
| ----- | ------ | ------- | -------- | ------------------------------- | ------------- |
| shell | string |         | yes      | shell to use to run the command | zsh/bash etc. |

### Default workflow

Default workflow will be created for you if you don't specify any workflows in the configuration. It will have the following configuration:

```yml
workflow_configuration:
  on_pull_request_pushed: [digger plan]
  on_pull_request_closed: [digger unlock]
  on_commit_to_default: [digger unlock]
```

## Workflow configuration explanation

Workflow configuration describes how to react to CI events. It has 3 sections:

- on_pull_request_pushed - describes what to do when pull request is created or updated

- on_pull_request_closed - describes what to do when pull request is closed

- on_commit_to_default - describes what to do when pull request is merged into default branch

## Projects

A project in Digger corresponds to a directory containing Terraform code. Projects are treated as standalone independent entities with their own locks. Digger will not prevent you from running plan and apply in different projects simultaneously.

You can run plan / apply in a specified project by using the -p option in Github PR comment:

```bash
digger apply -p my-second-app
```
